package com.matrix.api.marketing;

import com.matrix.api.marketing.dto.DynamicCouponGrantDTO;
import com.matrix.api.marketing.dto.RefundCalculationRequestDTO;
import com.matrix.api.marketing.vo.RefundCalculationResultVO;
import com.matrix.api.marketing.vo.UserCouponVO;

import java.math.BigDecimal;
import java.util.List;

/**
 * @author 有点甜
 * @since 2025/8/1
 */
public interface MarketingApi {

    /**
     * 新用户注册成功后,调用此接口发放新用户专享券
     *
     * @param userId 新用户的ID
     */
    void grantNewUserCoupon(Long userId);

    /**
     * 订单支付成功后,调用此接口为用户增加积分
     *
     * @param userId      用户ID
     * @param orderAmount 订单支付金额
     * @param orderId     订单ID
     */
    void addPointsForOrder(Long userId, BigDecimal orderAmount, String orderId);

    /**
     * 校验并使用优惠券
     *
     * @param userId       用户ID
     * @param userCouponId 用户持有的券ID
     * @param orderId      关联的订单ID
     * @return 优惠券的抵扣金额
     */
    BigDecimal useCoupon(Long userId, Long userCouponId, Long orderId);

    /**
     * 释放/返还优惠券
     *
     * @param userCouponId 用户持有的券ID
     */
    void releaseCoupon(Long userCouponId);

    /**
     * 由商家主动为用户发放一张动态生成的代金券
     *
     * @param grantDTO 包含动态券所有信息的DTO
     */
    UserCouponVO grantDynamicCouponByMerchant(DynamicCouponGrantDTO grantDTO);

    /**
     * 处理因部分退菜导致的优惠券和退款计算
     *
     * @param request 包含退款所需所有信息的DTO对象
     * @return 包含应退现金、应奖励积分等结果的VO对象
     */
    RefundCalculationResultVO processCouponForRefund(RefundCalculationRequestDTO request);

    /**
     * 根据用户持有的优惠券ID获取其抵扣金额
     *
     * @param userCouponId 用户持有的优惠券ID
     * @return 优惠券的面额，如果券不存在则返回 BigDecimal.ZERO
     */
    BigDecimal getCouponDiscount(Long userCouponId);

    /**
     * 获取用户的优惠券列表
     *
     * @param userId 用户ID
     * @param shopId 店铺ID
     * @return 用户的优惠券列表
     */
    List<UserCouponVO> getMyCoupons(Long userId, Long shopId);

    /**
     * 更新已使用优惠券关联的真实订单ID
     *
     * @param userCouponId 用户持有的券ID
     * @param orderId      真实的订单ID
     */
    void updateCouponOrderId(Long userCouponId, Long orderId);

}